Xbasic

Array find Method

Syntax

dim Index as N = <array>.find(A key[,C options[,N Starting]])

Arguments

keyAny Type: A value to find in the array.
optionsCharacter: An Xbasic expression that processes the array element before the find operation.
Starting: The index of the first array element to search.

Returns

IndexNumeric: Returns the index of the element in the array that matches the key. Returns 0 if no match is found.

Description

Find a value in the array, return the index of the entry, or 0 if not found.

Discussion

The <array>.find() method finds an element in a single dimensional array and returns its Index number.

In the case of a character, numeric, or logical array, options can be used to search on a value derived from the array entry. For example, setting options to "word(value, 1)" searches on the first word of each entry. Setting options to "lower(value)" makes the search case insensitive.

"Value" is a special keyword that refers to the value in the current array element.

In the case of a property array, options specifies which array property to search. For example:

dim a[2] as P
a[1].NAME = "sam"
a[1].city = "boston"
a[2].NAME = "celine"
a[2].city = "ithaca"
? a.find("celine","name") 
= 2.000000

If the array is a property array that contains a field named "index", find() will perform a case-insensitive search automatically on the index field without needing to define an expression to process array values before comparing them.

dim a[3] as P
a[1].index = "alpha"
a[1].number = 12
a[2].index= "beta"
a[2].number = 57
a[3].index = "Gamma"
a[3].number = 88

? a.find("gamma") ' performs case-insensitive comparison
= 3

Examples

dim A[2] as C
A[1] = "fred"
A[2] = "john"
? A.find("john") 
= 2

Assume you have the following array and want to search for sub-strings.

dim company[2] as C
company[1] = "Alpha Software Corporation"
company[2] = "International Computer Machines"

The following command searches for the array entry that contains the word "Software".

string = "Software"
? company.find(string,"word(value,word_FROM_pos(value,at(string,value)))") 
= 1

string = "software"
? company.find(string,"word(value,word_FROM_pos(value,at(string,value)))") 
= 0

'above does not find the string because search is case-sensitive
'to perform a case-insensitive search use atc()
? company.find(lower(string),"lower(word(value,word_FROM_pos(value,atc(string,value))))")
= 1

'The following command search for a substring.
string = "uter"
? company.find(string,"iif(occurs(string,value)>0,string,\"\")")
= 2